10 Command Line Reference

Here we present the syntax of the Wafl command line interpreter. This document is generated automatically. To get the current command line options, please run:

clwafl -help

The name of the Command line interpreter program may differ, depending on the installation package. It can be clWafl, clwafl or wafl.

10.1 Command Line Options

Usage: 
  to run a program:
    clwafl [<options>] <program file name> [<arguments>]

  to run inline source code:
    clwafl [<options>] -code "<source code>" [-args <arguments>]

  to apply some tools:
    clwafl [<options>] [<program or library file name>]

where <options> is a space separated list that can contain 
the following options:

  Program arguments and environment:
    -code "<source code>"
                  Specify the Wafl program code inline, as a part of the
                  command line. Quotes are strongly recommended.
    -args <args>  Specify Wafl program command line arguments.
                  Allowed only if inline source code is used.
    -dir:<app directory>
                  Specify the application directory.
                  Default is the path of the program file, or '.'.
    -workdir:<working directory>
                  Specify the working directory.
                  Default is program file path, or '.'.
    -libdir:<lib directory>
                  Specify a library search directory.
    -lib:<name>:<file>
                  Load Wafl library <file> as parameterized library <name>.
    -env:<env.var.name>=<env.var.value>
                  Define an environment variable.

  Database access:
    -dbdriver:<database driver>
                  Select a database driver.
    -db:<database alias>
                  Select a database alias.
    -user:<database connection username>
                  Specify the database user.
    -pwd:<database connection password>
                  Specify the database user's password.

  Runtime options:
    -repeat:<n>   Run the program <n> times.
    -memory       Print the memory report.
    -timer        Measure execution time.
    -title:<a title>
                  Set the title of the console window.
    -wait         Wait for a key after execution.

  Optimization and evaluation mode options:
    -stack-std, -stdstack
                  Use standard stack.
    -stack-ext, -extstack
                  Use extendable stack (default).
    -stack-size:<n>
                  Initial stack size in MiB [0-1024].
                  For extendable stack, the size of the first segment.
                  For standard stack, this is the stack size.
                  The default is 0, which means OS defined.
    -stack-blocksize:<n>
                  Single extendable stack block size in KiB [250-100000].
                  Only applies to extendable stack. The default is 1024KiB.
    -stack-limit:<n>
                  Total stack space limit for all threads together in MiB.
                  Only applies to extendable stack. Range is [0-100000].
                  The default is 0, which means 'unlimited'.
    -stack-threadlimit:<n>
                  Maximum permitted stack size in MiB [0-100000].
                  Only applies to extendable stack.
                  The default is 0, which means 'unlimited'.
    -jit          JIT optimization [experimental].
    -jit-rebuild  JIT optimization with module rebuild [experimental].
    -jit-ast      JIT optimization on AST [experimental].
    -jit-aeg      JIT optimization on AEG [experimental].
    -dis-tailcalls  
                  Disable tail calls optimization.

  Parallelization options:
    -pd, -parallel-disable
                  Disable implicit parallelization (default).
    -pa, -parallel-auto
                  Enable implicit parallelization.
    -ps, -parallel
                  Suggest the implicit parallelization. Like auto,
                  but biased more towards parallelization.
    -pf, -parallel-force
                  Use parallelization wherever possible.

  Debugging and testing options:
    -debug        Use the debug mode.
    -options      Print all selected options.
    -msgs         Print the compilation messages.
    -segvcatch    Use `segvcatch` library to catch system signals.
    -nornd        Run without initialization of random number generator.
                  The same `random` number sequence is generated each time,
                  except when parallel functions are used.
    -short        Print only a short preview of the program result.

  Tools:
    -check        Check whether a program or library is correct.
    -checkdir     Check whether all programs in the current directory
                  are correct.
    -checkdir:<dir>
                  Check whether all programs in <dir> are correct.
    -checkapp     Check whether all programs in the current directory
                  and its subdirectories are correct.
    -checkapp:<dir>
                  Check whether all programs in the directory <dir> 
                  and its subdirectories are correct.
    -parserast    Print the abstract syntax tree generated by parser.
    -parsersrc    Print the source code generated from the AST
    -builderaeg   Print the abs. evaluation graph generated by the builder.
    -buildersrc   Print the 'meta' source code generated from the AEG.
    -doc          Generate documentation based on the program comments.
                  Works for programs and Wafl libraries.
    -listlib      List the system library contents.
                  Dynamic libraries are excluded.
    -listlib:<w>  List the system library elements with names containing <w>,
                  or the content of a dynamic library with filename <w>.
    -create-ini-file 
                  Generate `wafl.ini` file in the working directory.

  Additional options:
    -help         Print this usage description.
    -version      Print version description.
    -verbose      Print further details on -listlib, -version and -memory.

10.2 Configuration Files

Configuration files are defined on three basic levels:

Global configuration defines options that apply to all users and all Wafl programs, until they are overriden. Global configuration is specified in file c:\ProgramData\wafl.ini for Windows, or /etc/wafl.ini for Linux.
User configuration defines the user specific options. They can override the global options and apply to all programs started by the user, if not overridden by local configuration. User configuration is specified in file %USERPROFILE%\.wafl.ini (usually C:\Users\<username>\) for Windows or ${HOME}/.wafl.ini (usually /home/<username>/) for Linux.
Local configuration defines the application specific options. They can override the global and user configurations. Local configuration is specified in file wafl.ini in working directory. It is used only for command line programs.

When a command line Wafl program is started, the configuration files are processed (global, user and local) and used as default values of program options. If an option is explicitly specified using the command line options, then it overrides the default values set in configuration files.

In the same way, for non-command line Wafl programs (Web service, Jupyter and others) a service configuration file can override some of the more general configuration parameters. For such programs the local configuration is not used.

Wafl configuration files use the common ini-file syntax.

[section-name-1]
par-name-1 = value-1
par-name-2 = value-2
# comment

[section-name-2]
par-name-3 = value-1
par-name-4 = value-2
# comment
...

Sections and Parameters

The following sections are defined:

command-line - defines the parameters that correspond to command line options, and represent their default values;
jit-g++ - defines the parameters for JIT compilation and linking using g++ tools;
jit-msvc - defines the parameters for JIT compilation and linking using MS Visual Studio.

Other sections can be defined in future.

Section `command-line`

For each command line option -option and parameter -param:value there is a corresponding parameter in the command-line section:

To define an option -option to be set by default, specify the parameter option = 1.
To define an option -option to be reset by default, specify the parameter option = 0.
If there is a set of mutually exclusive options, select the default one option-mode = name (see parallel or stack).
To define a default parameter value, specify param = value.
If a parameter can be used multiple times, add -NN to its name. Such parameters are used in a lexical order.

Here is an example configuration for command-line section, with all applicable parameters:

[command-line]
# This section defines the default command line program options.
# For each parameter, the corresponding command line option 
# is specified in the comment.

# Default database driver 
#   -dbdriver:<value>
db-driver = Odbc
# Set default database 
#   -db:<value>
db = Test

# DB connection username and password 
# must not be specified in configuration file!

# Set environmet variables 
#   -env:<name>=<value>
env-01 = DATA_PATH = /data
env-02 = MEDIA_PATH = /data/media

# Default system library directory 
# Cannot be overriden by command line options!
# The default is `${WAFL_PATH}/lib`, but if another version
# of the system library is used (e.g. during the development)
# then it can be specified here. 
libdir-system = /dev/Wafl/lib
# Default application library directory 
#   -libdir:<value>
libdir = ~/mywafllibs
# Load a parametrized library by default
#   -lib:<name>:<file>
lib-01 = libOs = myoslib
lib-02 = libDb = mydblib

# Set parallelization mode [auto, disable, suggest, force]
#   -pa, -pd, -ps, -pf
parallel-mode = auto

# Use extendable stack [extendable, standard]
#   -stack-ext, -stack-std
stack-mode = extendable
# Initial steck size in MiB
#   -stack-size:<value>
stack-size = 10
# Size of individual stack blocks in KiB
#   -stack-blocksize:<value>
stack-blocksize = 1000
# Total stack limit for all threads together in GiB
#   -stack-limit:<value>
stack-limit = 0
# Stack limit for individual threads in MiB
#   -stack-threadlimit:<value>
stack-threadlimit = 1000

# Use JIT
#   -jit
jit = 0
# Default JIT mode [aeg, ast]
# NOTE: This option does not turn JIT on!
#   -jit-aeg, -jit-ast
jit-mode = aeg
# Set JIT rebuild by default
# NOTE: This option does not turn JIT on!
#   -jit-rebuild
jit-rebuild = 0

# The other aplicable parameters 
# Please see command line options for details
title = My Wafl command line window title
timer = 0
wait = 0
debug = 0
segvcatch = 0
dis-tailcalls = 0
nornd = 0

Section `jit-g++`

Here is a complete example, for Ubuntu Linux 24.10, g++ and appropriate Wafl Core:

[jit-g++]
include-path-1 = /home/smalkov/dev/WaflLocal/bld/debug/_install/waflcore/GNU_12.4.0_uxmkfl_x86_64_8_1_CPP20_Debug/include

compiler-options-1 = -std=c++20 -fpic -ldl -shared 
compiler-options-release = -O3 -DNDEBUG

link-options-1 = ~/dev/WaflLocal/bld/debug/_install/waflcore/GNU_12.4.0_uxmkfl_x86_64_8_1_CPP20_Debug/lib/libWaflCore.a;

#keep-source = 1

Please see JIT documentation for details.

Section `jit-msvc`

Here is a complete example, for VS 2022, Windows 10 and appropriate Wafl Core:

[jit-msvc]
tools-path = C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.42.34433\bin\Hostx64\x64

include-path-1 = C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.42.34433\include
include-path-2 = C:\Program Files (x86)\Windows Kits\10\include\10.0.22621.0\ucrt
include-path-3 = E:\Wafl\bld\vs17_release\_install\waflcore\MSVC_143_win64_AMD64_8_1_CPP20_Release\include

lib-path-1 = C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.42.34433\lib\x64
lib-path-2 = C:\Program Files (x86)\Windows Kits\10\lib\10.0.22621.0\ucrt\x64
lib-path-3 = C:\Program Files (x86)\Windows Kits\10\lib\10.0.22621.0\um\x64
lib-path-4 = E:\Wafl\bld\vs17_release\_install\waflcore\MSVC_143_win64_AMD64_8_1_CPP20_Release\lib

compiler-options-1 = /nologo /std:c++20 /EHsc /Gd /MP
compiler-options-2 = /Fo: "%TEMP%"
compiler-options-3 = /D _WINDLL /D _ITERATOR_DEBUG_LEVEL=0 /D WIN32 /D _WINDOWS /D _WIN32_WINNT=0x0A00
# compiler-options-debug = /MTd /Od /Ob0
compiler-options-release = /MT /O2

link-options-1 = /NOLOGO /DLL /DYNAMICBASE /MACHINE:X64 /LTCG /NOIMPLIB /NOEXP
link-options-2 = libWaflCore.lib 
link-options-3 = kernel32.lib user32.lib gdi32.lib winspool.lib shell32.lib ole32.lib oleaut32.lib uuid.lib comdlg32.lib advapi32.lib

#keep-source = 1

Please see JIT documentation for details.

10.3 ANSI Control Codes

Wafl supports ANSI console control codes, often referred to as ANSI escape sequences. The control sequences are printed to the console like ordinary text, but allow control of color, font, cursor position and other options.

The Wafl library Console.wlib contains many predefined sequences. It can be used to write more readable Wafl code. For example, the following two code segments generate and output the same result:

"Regular\e[34mBlue\e[0mRegular"

"Regular"
+ con::colorFgBlue + "Blue" + con::resetColor
+ "Regular"

where {
  con = library file 'Console.wlib';
}